home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
JCSM Shareware Collection 1993 November
/
JCSM Shareware Collection - 1993-11.iso
/
cl720
/
prolc1j.lzh
/
PPL4C.USR
< prev
next >
Wrap
Text File
|
1992-08-23
|
50KB
|
1,322 lines
Personal Protocol Library
For the C Language
(PPL4C)
USERS MANUAL
Version 1.0
Aug 16, 1992
This software is provided as-is.
There are no warranties, expressed or implied.
Copyright (C) 1992
All rights reserved
MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815
Phone (205) 881-4630
PPL4C Users Manual Page 1
C O N T E N T S
Chapter Page
1.0 Introduction..............................................3
1.1 Compiling the Library.................................3
1.2 User Support..........................................4
1.3 Installation..........................................5
2.0 State Drivers.............................................6
3.0 File Transfer Protocols...................................7
3.1 XMODEM................................................7
3.2 XMODEM-CRC............................................9
3.3 XMODEM-1K.............................................9
3.4 XMODEM-G.............................................10
3.5 YMODEM...............................................10
3.6 YMODEM-G.............................................10
4.0 Protocol Library Functions...............................11
4.1 xyAbort..............................................11
4.2 xyDriver.............................................11
4.3 xyGetErrorCode.......................................12
4.4 xyGetErrorState......................................12
4.5 xyGetFilename........................................12
4.6 xyGetNAKs............................................12
4.7 xyGetPacket..........................................12
4.8 xyGetState...........................................12
4.9 xyInit...............................................13
4.10 xyStartRx...........................................13
4.11 xyStartTx...........................................13
5.0 The FILEXFER.C Demonstration Program.....................14
5.1 Introduction.........................................14
5.2 The FILEXFER.H Parameter File........................15
5.3 Running FILEXFER.....................................16
6.0 Using The Protocol Library...............................17
6.1 Keyboard Input.......................................17
6.2 Disk I/O.............................................18
6.3 Serial I/O...........................................18
6.4 Other Events.........................................18
7.0 Problems.................................................19
8.0 Legal Issues.............................................20
8.1 Registration.........................................21
8.2 License..............................................21
8.3 Warranty.............................................21
9.0 Revision History.........................................21
10.0 Other MarshallSoft Computing Products....................22
10.1 The Personal Communications Library for C...........22
10.2 The Personal Communications Library for Pascal......22
PPL4C Users Manual Page 2
1.0 Introduction
The Personal Protocol Library (PPL) consist of a state driven
library which implements the XMODEM, XMODEM-CRC, XMODEM-1K,
XMODEM-G, YMODEM, and YMODEM-G file transfer protocols. This
allows the programmer to run multiple protocol transfers
simultaneously while interacting with the user at the keyboard.
The PPL requires the Personal Protocol Library (PCL), also
available from MarshallSoft Computing. The user should be
familiar with PCL before attempting to understand the protocol
driver. Refer to section "Other MarshallSoft Computing Products".
What are the advantages of a state driven protocol library ? The
answer is any type of communications program which requires
"background" protocol file transfers. A few examples are:
(1) EXAMPLE-1: A program that can read incoming stock market data
continuously while the main application is doing technical
analysis.
(2) EXAMPLE-2: A custom BBS program that can handle two file
transfers simultaneously.
See the section 8.1 "Registration" for an offer who might not want
to refuse!
1.1 Compiling the Library
There are three small model library files provided:
ppl4c_sb.lib -- Borland Turbo C library.
ppl4c_sm.lib -- Microsoft C library.
ppl4c_sx.mix -- MIX Power C library.
The registered user can recompile the source code (source code is
provided in the registered version only) for the library using one
of the three provided batch files:
make_sb.bat -- make small Borland Turbo C library (ppl4c_sb.lib).
make_sm.bat -- make small Micrsoft C library (ppl4c_sm.lib).
make_sx.bat -- make small MIX Power C library (ppl4c_sx.mix).
PPL4C Users Manual Page 3
1.2 User Support
We want you to be successful in developing your applications using
PPL4C! We depend on our customers to let us know what they need
in a protocol library. This means we are committed to providing
the best communications library that we can. If you have any
suggestions or comments, please write to us or give us a call.
If you are having a problem using PPL4C, call (205) 881-4630
between 5 PM and 9 PM CST Monday through Saturday. You can call at
other times and leave a message, and call back later during our
regular business hours for a reply. You can also FAX us at this
same number at any time.
You may also call our 24 hour BBS (2400 baud, no parity, 8 data
bits, 1 stop bit) at any time. The BBS will contain the latest
shareware version of PPL4C, messages, and other related files. All
files are in standard ZIP format. You can leave a message on the
BBS, and we will usually have a reply ready for you within 24
hours. The dedicated telephone number is 205-880-9748. Set your
modem for 2400 baud, 8 data bits, no parity, one stop bit.
The MarshallSoft Computing, Inc. newsletter "Comm Talk" is
published quarterly. It discusses various communications problems
and solutions using PCL4C (the communications library) and PPL4C
(the protocol library) as well as related information. Registered
users receive a one year complimentary subscription when first
registering and for each update purchased.
Of course, you can always write to us. You should receive a reply
within one to two weeks.
PPL4C Users Manual Page 4
1.3 Installation
(1) Before installation of PPL4C, your C compiler should already
be installed on your system and tested. If you are not familiar
with makefiles, refer to your compiler manual. If you are using
the interactive environment for Quick C or Turbo C, be sure to
compile with the memory model corresponding to the PPL4C library
used. Examine the file "FILES.LST" for a list of all the
distribution files.
(2) Make a backup copy of your distribution disk. Put your
original distribution disk in a safe place.
(3) Create a work directory on your work disk (normally your
harddisk). For example, to create a work directory named PPL4C, we
first log onto the work disk and then type:
MKDIR PPL4C
(4) Copy all the files from your backup copy of the distribution
disk to your work directory. For example, to copy from the A:
drive to your work directory, we type:
CD PPL4C
COPY A:*.*
(5) [OPTIONAL] Delete the makefiles that you won't need. For
example, if you use the Microsoft C compiler, then you want to
keep all makefiles ending *._M_ but can delete those for Turbo C
(*._T_), Quick C (*._Q_), and MIX Power C (X_*.BAT). You may also
delete any libraries that you won't need.
(6) Compile FILEXFER.C and link with the appropriate PPL4C library
(PPL4C_SM.LIB for Microsoft C, PPL4C_SB.LIB for Borland Turbo C,
and PPL4C_SX.MIX for MIX Power C). MAKEFILES (or project files)
are provided for each of the supported compilers.
a) Microsoft C: Type MAKE FILEXFER._M_
b) Microsoft Quick C: Type MAKE FILEXFER._Q_
c) Borland Turbo C: Type MAKE -FFILEXFER._T_
d) MIX Power C: Type X_FILEXFER
FILEXFER.C should compile without any problems as all example code
has been tested with each of the supported compilers.
(7) The recommended way to test FILEXFER is to run it on two
computers connected by a null modem cable. See section
"Problems" for a recommended approach to testing FILEXFER.
PPL4C Users Manual Page 5
2.0 State Drivers
A state driver is a programming technique in which a typically
complex task in broken down into small steps known as states. Each
state can be executed relatively quickly, and in particular never
does any waiting. The main application program calls the state
driver whenever it is waiting for a user keypress, or at any other
arbitrary time. The effect is that the state driven code executes
whenever the main application code is not working.
The Microsoft Windows operating system uses a variation on the
state driven technique. Think of each running program as a state.
The operating system calls each state in turn (unlike the protocol
driver, the states are independent). Each state (or program) must
yield the processor (by getting the next input event) or by
explicitly calling a yield function. The operating system cannot
force any running program to yield the processor.
Coding a file transfer protocol as a state driver allows
simultaneous file transfers to occur. Although the driver is
written for a maximum of two ports since the their are at most 2
serial interrupts available on standard PCs, there is no reason
that the driver could not handle more than two simultaneous
transfers.
The central difficulty is using a state driver for XMODEM and
YMODEM is that those protocols time out if they have to wait too
long for a response. The solution is to call the driver at
approriate times. In other words, the state driver must be called
often enough to prevent a protocol timeout.
The XMODEM and YMODEM protocol timeout values in the state driver
are longer than a strict implementation of the protocol standards.
This eases the timing requirements somewhat. However, if the other
side of the transfer is running a strict implementation of XMODEM
or YMODEM then we can still have protocol timeout problems.
The following section "File Transfer Protocols" provides a
general understanding of XMODEM and YMODEM. In particular, pay
attention to the timeout requirements.
PPL4C Users Manual Page 6
3.0 File Transfer Protocols
3.1 XMODEM
XMODEM refers to the file transfer protocol introduced by Ward
Christensen in 1977. XMODEM is widely supported on most all
bulletin board systems.
The following ASCII character definitions are used in XMODEM.
<SOH> = 01H Is always the first byte in each block.
<EOT> = 04H Sent instead of SOH to mark the end of transmission.
<ACK> = 06H Positive acknowledgment.
<NAK> = 15H Negative acknowledgment.
<CAN> = 18H Cancel transfer.
XMODEM is a receiver driven, asynchronous, 8 data bit protocol.
Each packet looks like the following:
<SOH> <packet #> <compliment #> <data> <checksum>
where <SOH> = 01H.
<packet #> = Packet number, starting at 01, incrementing by 1, and
wraps from 0FFH to 00H (not to 01H).
<compliment #> = 255 minus the packet number.
<data> = 128 bytes of binary data.
<checksum> = The sum of the data bytes. Starting with a zero add
each data byte to the checksum. Use only the rightmost 8 bits.
When the receiver is ready, it sends a NAK every 10 seconds ( up
to one minute ) until the NAK is ackowledged by the transmitter by
sending the first packet. The transmitter continues by sending
each packet in turn, always waiting for the packet to be
ackowleged before sending the next. Finally, when the transmitter
has no more data, it sends an EOT instead of a SOH to complete the
transfer.
Each packet is sent by the transmitter as follows:
(1) Each packet always starts with a SOH.
(2) The packet number is sent next, starting with 01H, and
incrementing by 1. The packet number wraps from 0FFH to 00H.
(3) The packet number compliment is sent next. It is always
calculated a 255 minus the packet number.
(4) Exactly 128 bytes of data is sent. If the transmitter doesn't
have 128 bytes of data to send, then control-Z's (1AH) are padded
to the data block.
PPL4C Users Manual Page 7
(5) The checksum is calculated by added together all 128 data
bytes and sending the least significant 8 bits.
(6) The transmitter waits ( up to 10 seconds ) for a response. If
the response is an ACK, then the transmitter goes on to the next
packet. If the response is a NAK, then the transmitter re-sends
the entire packet. If the response is a CAN, then all further
transmission is cancelled.
Each packet is handled by the receiver as follows:
(1) If the first character is an EOT then the transfer is now
complete, and the receiver should ACK the EOT before exiting. If
the first character is a CAN, then all further action is
cancelled. If the first character is a SOH, then this is the first
character of the next packet.
(2) If the packet number is not correct ( the first packet is 1 ),
then this is a fatal error, and the receiver should send a CAN to
the transmitter in order to cancel further transmission.
(3) If the packet number compliment is not correct, this is also a
fatal error and the receiver sends a CAN to the transmitter.
(4) Exactly 128 bytes of data are received.
(5) The checksum is received. It is compared with the value
obtained by computing the checksum from the just received data. If
the checksum values are the same, an ACK to sent to the
transmitter. Otherwise, a NAK is sent.
Here is a XMODEM example of the data flow. It includes the two
most common line hits: a garbaged block, and an <ACK> reply
getting garbaged. <data> represent 128 bytes of data. <CS>
represents the checksum byte.
SENDER RECEIVER
====== ========
<--- <NAK>
<SOH> 01 FE <data> <CS> --->
<--- <ACK>
<SOH> 02 FD <data> <CS> ---> (data gets line hit)
<--- <NAK>
<SOH> 02 FD <data> <CS> --->
<--- <ACK>
<SOH> 03 FC <data> <CS> --->
(ACK gets garbaged) <--- <ACK>
<SOH> 03 FC <data> <CS> ---> <ACK>
<EOT> --->
<--- <anything except ACK>
<EOT> --->
<--- <ACK>
PPL4C Users Manual Page 8
3.2 XMODEM-CRC
The XMODEM-CRC protocol is similar to the XMODEM protocol, except
that the receiver specifies CRC-16 by sending C (Hex 43) instead
of NAK when requesting the FIRST block. A two byte CRC is sent in
place of the one byte arithmetic checksum.
3.3 XMODEM-1K
The XMODEM-1K protocol is identical to XMODEM-CRC, except that
1024 byte data blocks in addition to 128 byte data blocks can be
sent. An STX (02H) replaces the SOH (01H) at the beginning of the
transmitted block to notify the receiver of the longer block
length. The transmitted block contains 1024 bytes of data. The
receiver should be able to accept any mixture of 128 and 1024 byte
blocks. The block number (in the second and third bytes of the
block) is incremented by one for each block regardless of the
block length.
The sender must not change between 128 and 1024 byte block lengths
if it has not received a valid ACK for the current block.
Here is an example of XMODEM-1K with 1024 blocks:
SENDER RECEIVER
====== ========
C
STX 01 FE Data[1024] CRC CRC
ACK
STX 02 FD Data[1024] CRC CRC
ACK
STX 03 FC Data[1000] ^Z[24] CRC CRC
ACK
EOT
ACK
Mixed 1024 and 128 byte Blocks
SENDER RECEIVER
====== ========
C
STX 01 FE Data[1024] CRC CRC
ACK
STX 02 FD Data[1024] CRC CRC
ACK
SOH 03 FC Data[128] CRC CRC
ACK
SOH 04 FB Data[100] ^Z[28] CRC CRC
ACK
EOT
ACK
PPL4C Users Manual Page 9
3.4 XMODEM-G
The XMODEM-G protocol works like XMODEM-1K except that the sender
never waits for a packet ACK. This results in a faster transfer
than would otherwise occur. However, hardware flow control (RTS -
CTS) must be turned on. Be carefull if you are using a null modem
cable for PC to PC transfer since many null modem cables do not
exchange RTS and CTS as required. Refer to the Personal
Communication Library Users Manual for a discussion of flow
control.
3.5 YMODEM
The YMODEM Batch protocol is an extension to the XMODEM-1K
protocol that allows 0 or more files to be transmitted in a single
session. YMODEM always sends an information packet (number 0) with
each file containing the filename and the file length.
The filename is sent as a null terminated ASCII string. This is
the filename format used by the handle MSDOS oriented functions.
The length field is sent as a decimal ASCII string counting the
number of data bytes in the file. The file length does not
include any ^Z or other characters used to pad the last block. All
unused bytes in packet 0 must be set to 0.
After the file has been transmitted, the receiver asks for the
next file by sending a 'C'. Transmission of a null pathname
terminates the YMODEM protocol. An EOT is not transmitted after a
null pathname. Here is an example of YMODEM:
SENDER RECEIVER
====== ========
C
C
SOH 00 FF Filename NULs CRC CRC
ACK
C
STX 01 FE Data[1024] CRC CRC
ACK
STX 02 FD Data[1024] CRC CRC
ACK
SOH 03 FC Data[128] CRC CRC
ACK
SOH 04 FB Data[100] ^Z[28] CRC CRC
ACK
EOT
ACK
C
SOH 00 FF NUL[128] CRC CRC
ACK
3.6 YMODEM-G
YMODEM-G is similiar to XMODEM-G in that the sender never waits
for a packet ACK. Refer to the section "XMODEM-G".
PPL4C Users Manual Page 10
4.0 Protocol Library Functions
There are 11 protocol library functions. Their prototypes are in
file xyDriver.h and are as follows:
int xyAbort(int);
int xyDriver(int);
int xyGetErrorCode(int);
int xyGetErrorState(int);
char *xyGetFilename(int);
int xyGetNAKs(int);
int xyGetPacket(int);
int xyGetState(int);
int xyInit(int,int);
int xyStartTx(int,char *,int,int);
int xyStartRX(int,char *,char,int);
All state driver functions return a negative value for a
communications error. See the PCL4C manuals for a list of these
errors.
The function xyInit should be called after initializing the
selected port with SioReset. Then, either xyStartTx or xyStartRx
should be called to initiate file transfer. The file transfer is
done when xyDriver return a 0 (NO_ERROR).
Examine the library test program FILXFER.C for an example of the
proper use of the state driver functions.
4.1 xyAbort
int xyAbort(C)
int C; /* channel (0 or 1) */
The xyAbort functions aborts any file transfer occuring on channel
C and return the channel to the idle state. The protocol driver
will send a cancel command to the other end.
4.2 xyDriver
int xyDriver(C)
int C; /* channel (0 or 1) */
The xyDriver function should be called as often as possible.
Typically there are two places that it is called. The first is
whenever the main application is waiting for a keypress. This
should be implemented by forcing all keyboard input to go through
a user written keyboard input routine. Refer to the section
"Using the Protocol Library" for an example. xyDriver should also
be called periodically during any long operation such as disk I/O.
PPL4C Users Manual Page 11
4.3 xyGetErrorCode
int xyGetErrorCode(C)
int C; /* channel (0 or 1) */
The xyGetErrorCode function is called once xyDriver returns a
positive value indicating that it is complete. The user should
then call xyGetErrorCode to determine if there was an error in
the transfer and if so, what the error was.
4.4 xyGetErrorState
int xyGetErrorState(C)
int C; /* channel (0 or 1) */
The xyGetErrorState function is called to determine the state that
the protocol driver was in when the error occured. Don't call
xyGetErrorState unless an error has occured as determined by
calling xyGetErrorCode.
4.5 xyGetFilename
char *xyGetFilename(C)
int C; /* channel (0 or 1) */
The xyGetFilename function returns the name of the file that the
protocol driver is transfering. This is particularly useful when
multiple files are being transfered by YMODEM.
4.6 xyGetNAKs
int xyGetNAKs(C)
int C; /* channel (0 or 1) */
The xyGetNAKs function is used to return the accumulative number
of NAKed packets.
4.7 xyGetPacket
int xyGetPacket(C)
int C; /* channel (0 or 1) */
The xyGetPacket function returns the current packet number while a
protocol transfer is underway. Otherwise it return a -1.
4.8 xyGetState
int xyState(C)
int C; /* channel (0 or 1) */
The xyState function returns the current state of the protocol
driver. Refer to xyDriver.h for a list of all driver states and
their values.
PPL4C Users Manual Page 12
4.9 xyInit
int xyInit(C,Port)
int C; /* channel (0 or 1) */
int Port; /* Port (COM1 to COM4) */
The xyInit function should be called after initializing the
selected serial port. The first port should be assigned to channel
0 and the second, if defined, should be assigned to channel 1.
The channel number is used to identify the port in all subsequent
calls to state driver functions.
Recall that ports COM1 and COM3 can not be used simultaneously,
and that ports COM2 and COM4 cannot be used simultaneously.
4.10 xyStartRx
int xyStartRx(C,Filename,NCGchar,BatchFlag)
int C; /* channel (0 or 1) */
char *Filename; /* filename */
char NCGchar; /* startup character */
int BatchFlag; /* TRUE for YMODEM */
The xyStartRx function is called to start XMODEM / YMODEM as the
receiver. The correct flag values are as follows:
Protocol NCGchar BatchFlag
XMODEM NAK FALSE
XMODEM-CRC 'C' FALSE
XMODEM-1K 'C' FALSE
XMODEM-G 'G' FALSE
YMODEM 'C' TRUE
YMODEM-G 'G' TRUE
4.11 xyStartTx
int xyStartTx(C,Filename,OneKflag,BatchFlag)
int C; /* channel (0 or 1) */
char *Filename; /* filename */
int OneKflag; /* TRUE for XMODEM-1K and YMODEM */
int BatchFlag; /* TRUE for YMODEM */
The xyStartTx function is called to start XMODEM / YMODEM as the
sender. The correct flag values are as follows:
Protocol OneKflag BatchFlag
XMODEM FALSE FALSE
XMODEM-CRC FALSE FALSE
XMODEM-1K TRUE FALSE
XMODEM-G FALSE FALSE
YMODEM TRUE TRUE
YMODEM-G TRUE TRUE
PPL4C Users Manual Page 13
5.0 The FILEXFER Demonstration Program
5.1 Introduction
The FILEXFER demonstration program is capable of doing two
simultaneous protocol file transfers while interacting with the
user at the keyboard. This is accomplished by coding the protocol
transfer code as a state driver (refer to the previous section on
State Drivers).
The best way to run FILEXFER is to connect two PCs running a
communications program (such as the TERM program on the PCL4C
distribution diskette) to a third PC running FILEXFER, connected
by null modem cables.
If you only have two PCs, you can still run the FILEXFER
program with just one channel.
The FILEXFER demonstration program requires the Personal
Communications Library (PCL4C) to run. If you don't already have a
copy, you can find it on most of the larger information services
and bulletin boards such as CompuServe, GENIE, and Exec-PC. You
also can usually find it in the larger shareware disk distributor
libraries. Lastly, you can always download it from our 24 hour
BBS (205-880-9748 at 2400 baud, 8 data bits, no parity, 1 stop
bit).
Before attempting to run FILEXFER, try transfering files using the
TERM program on the PCL distribution disk. Start by transfering
files via XMODEM between two machines connected by a null modem
cable at 9600 baud. Once you have TERM working on both sides,
replace TERM by FILEXFER on one side.
FILEXFER has been found to run at speeds up to 38400 baud using
one channel and up to 19200 baud using two channels
simultaneously on a 386 machine. You ought to be able to run 9600
on most all machines.
PPL4C Users Manual Page 14
5.2 The FILEXFER.H Parameter File
The FILEXFER.H include file contains all the user changeable
parameters for the FILEXFER.C demonstration program.
Be sure to read the comments in the FILEXFER.H file.
5.2.1 The AT_COMMAND_SET parameter
The AT_COMMAND_SET parameter is used to specify that a Hayes AT
command set compatible modem will be connected to each port being
used (one or two as specified by NBR_OF_CHANNELS).
5.2.2 The RTS_CTS_CONTROL Parameter
The RTS_CTS_CONTROL parameter is used to specify if hardware flow
control is being used on all channels as specified by
NBR_OF_CHANNELS. If you define this parameter to be TRUE and you
are using a Null modem cable to connect two PC's together, be sure
that RTS and CTS are swapped just like TX and RX are swapped. In
many Null Modem cables, this is not the case.
5.2.3 The NBR_OF_CHANNELS Parameter
The NBR_OF_CHANNELS parameter specifies the number of concurrent
ports that you will run. The only two legal values are 1 and 2.
The first port specifies is known as channel 0 while the second
port (if NBR_OF_CHANNELS is defined to be 2) is known as channel
1.
5.2.4 The PRI_PORT Parameter
The PRI_PORT parameter specifies the primary port, which can be
COM1, COM2, COM3, or COM4. The primary port is associated with
channel 0.
5.2.5 The SEC_PORT Parameter
The SEC_PORT parameter specifies the secondary port. This
parameter is used provided that NBR_OF_CHANNELS is defined to be
2. Legal values of the secondary port are ( depending on the value
of the primary port):
PRI_PORT SEC_PORT
COM1 COM2 or COM4
COM2 COM1 or COM3
COM3 COM2 or COM4
COM4 COM1 or COM3
The secondary port is associated with channel 1.
PPL4C Users Manual Page 15
5.2.6 The PRI_BAUD Parameter
The PRI_BAUD parameter specifies the baud rate associated with the
primary port (channel 0). Limit the baud rate to 19200 if you are
running two ports simultaneously.
5.2.7 The SEC_BAUD Parameter
The SEC_BAUD parameter specifies the baud rate associated with the
secondary port (channel 1). Limit the baud rate to 19200 if you
are running two ports simultaneously.
5.3 Running FILEXFER
To run the FILEXFER program, follow these steps:
(1) Edit the FILEXFER.H parameters file. Be conservative the first
time you run FILEXFER. Use one channel and a baud rate of 9600.
After you have run FILEXFER successfully with one port, then you
can try two ports.
(2) Compile FILEXFER and link with the PPL and PCL libraries.
Use the provided makefile:
FILEXFER._T_ for the Borland Turbo C compiler.
FILEXFER._M_ for the Microsoft Optimizing compiler.
FILEXFER._Q_ for the Microsoft Quick C compiler.
X_FILEXF.BAT for the MIX Power C compiler.
(3) Run FILEFER on one PC connected to one or two other PCs
running a communications program such as TERM.
(4) Start XMODEM receive in FILEXFER, then start XMODEM send on
the connected PCs. As the file protocol progresses, you can
monitor it's state by selected the "C)omm Status" choice from the
FILEXFER menu.
The one line FILEXFER menu is:
Q)uit P)rotocol S)end R)eceive A)bort C)omm Status
The menu line allows the user to:
(1) Quit FILEXFER.
(2) Set the protocol (XMODEM,XMODEM-CRC,XMODEM-1K,YMODEM,YMODEM-G)
(3) Send a file (wildcards accepted). Channel must be idle.
(4) Receive a file.
(5) Abort a file transfer. Returns channel to idle state.
(6) Get driver status. Reports current state and packet.
PPL4C Users Manual Page 16
6.0 Using The Protocol Library
Before attempting to use the protocol library, be sure to run the
demonstration program FILEXFER. Only when you are satisfied that
FILEXFER runs correctly should you attempt to use the protocol
library in your own application.
There are only a few hard rules to follow in order to use the
protocol library successfully. The first is that you absolutely
must call xyDriver often. There is no way that the state driver
library can operate without timing out if you don't.
6.1 Keyboard Input
You must always call xyDriver when waiting for a keypress. This
means that all keyboard input should be called through a central
keyboard input routine. For example, if you are running two
channels:
int ReadKey()
{while(!SioKeyPress())
{xyDriver(0);
xyDriver(1);
}
return( SioKeyPress() );
} /* end ReadKey */
#define CR 0x0d
int ReadString(String)
char String[];
{char x;
int i;
for(i=0;;i++)
{x = ReadKey();
if(x==CR)
{String[i] = '\0';
return(i);
}
else String[i++] = x;
} /* end for */
} /* end ReadString */
int ReadInteger()
{char Buffer[40];
int Length;
Length = ReadString(Buffer);
return(atoi(Buffer));
} /* end ReadInteger */
float ReadFloat()
{char Buffer[40];
int Length;
Length = ReadString(Buffer);
return(atof(Buffer));
} /* end ReadInteger */
PPL4C Users Manual Page 17
6.2 Disk I/O
In general, reading from a harddisk is not a problem if you call
xyDriver after after 1000 bytes or so. Don't attempt to read
or write too large a block of data.
Don't do disk I/O to a floppy while the protocol driver is running
(not in the idle state). However, it is OK to let the protocol
driver read and write to a floppy disk provided that the other
channel is not also doing floppy disk I/O.
6.3 Serial I/O
You can do serial I/O while the protocol driver is running
provided that you are using a port (and interrupt) different from
the one that the protocol driver is using. However, you must not
wait for any input. This means that you should not attempt to read
more characters from the input buffer than is returned by
SioRxQue. And, remember to call the protocol driver often. Don't
read or write more than 1000 bytes without calling xyDriver.
6.4 Other Events
In general, you can process any event provided that you don't take
too long ! Remember that when the protocol driver is transfering
files, it is expecting certain handshaking operations to be
performed in a certain maximum amout of time. If that time is
exceeded, then a protocol timeout error occurs. Even though we
have relaxed the timeing restrictions within the protocol driver,
the other end of the serial line (another XMODEM or YMODEM
program) expects not to have to wait too long before cancelling a
transfer session.
Just remember to call xyDriver often. If you are experiencing
timeout errors, insert more calls to xyDriver.
PPL4C Users Manual Page 18
7.0 Problems
If you can't get FILEXFER to run, try the following procedure:
(1) Connect two PCs together using a null modem cable. Run the
TERM program (from the PCL distribution diskette) on both
machines at 2400 baud. If you can't get TERM to run, refer to your
PCL (Personal Communications Library) manuals for help.
(2) Once TERM is running correcly, try transferring files using
XMODEM. Start the receiver side first.
(3) Replace TERM on one machine with FILEXFER. Be sure to set the
baud rate and port in the FILEXFER.H file and re-compile as
necessary.
(4) Try a XMODEM transfer first. If this works, then try a YMODEM
transfer.
Once the above is working, you might try adding a third machine
and have FILEXFER do two file transfers simulaneously.
If you can get FILEXFER to work correctly at 2400 baud but not at
a higher baud rate, you might consider using 16550 UARTs. They can
be programmed (using SioFIFO) to buffer up to 14 characters before
generating an interrupt.
We can help you get FILEXFER running, but we cannot help you debug
your application. The central difficulty is in calling xyDriver in
time to prevent a protocol timeout. This can be a tough problem.
Study FILEXFER to see how it can be done.
PPL4C Users Manual Page 19
8.0 Legal Issues
8.1 Registration
The shareware version of PPL4C.LIB is provided so that you may
personally determine the usefulness of the product for yourself.
If you can use the Personal Protocol Library for C, please
register your use with us. Send $35 plus $3 S&H ($6 outside of
North America) to:
MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815
The user may also order both the Personal Communications Library
(PCL4C) and the Personal Protocol Library (PPL4C) at the same time
for $65. Registered users of PCL4C can order the protocol library
PPL4P for $25 and also receive the latest version of PCL4C for no
extra charge.
Please pay by check in US dollars drawn on a US bank. Purchase
Orders (POs) are accepted from recognized US schools and companies
listed in Dunn & Bradstreet. Print the file PPL4C.INV if an
invoice is needed. The registered package is mailed first class US
Mail (packet air mail overseas). If you are in a hurry, please
call us and we can ship immediately within the USA by COD (street
address and phone number required).
The registered package includes:
o No shareware screen.
o C source code for the library.
o Printed Users Manual.
o Telephone / FAX / BBS support for one year.
o One year subscription (quarterly) to MSC newsletter.
o All updates (with printed manuals) are $15 plus $3 S&H
($6 outside of North America). Updates for PCL4C and PPL4C
together are $25.
PPL4C.C is the source code for the library. The source code is
copyrighted by MarshallSoft Computing, Inc. The user is granted a
license to use the PPL4C object code in his own application only.
PPL4C.C is not shareware and may not be sold or given away to
anyone.
The registered user will receive the latest version of PPL4C by
return mail. A 5.25" diskette is provided unless a 3.5" diskette
is requested.
PPL4C Users Manual Page 20
8.2 License
MarshallSoft Computing, Inc. grants the registered user of PPL4C
the right to use the PPL4C library (in object form) in the
development of any software product without any royalties.
However, the source code for the library may not be released in
whole or in part.
8.3 Warranty
MARSHALLSOFT COMPUTING, INC. DISCLAIMS ALL WARRANTIES RELATING TO
THIS SOFTWARE, WHETHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT
LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
FOR A PARTICULAR PURPOSE, AND ALL SUCH WARRANTIES ARE EXPRESSLY
AND SPECIFICALLY DISCLAIMED. NEITHER MARSHALLSOFT COMPUTING, INC.
NOR ANYONE ELSE WHO HAS BEEN INVOLVED IN THE CREATION, PRODUCTION,
OR DELIVERY OF THIS SOFTWARE SHALL BE LIABLE FOR ANY INDIRECT,
CONSEQUENTIAL, OR INCIDENTAL DAMAGES ARISING OUT OF THE USE OR
INABILITY TO USE SUCH SOFTWARE EVEN IF MARSHALLSOFT COMPUTING,
INC. HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR
CLAIMS. IN NO EVENT SHALL MARSHALLSOFT COMPUTING, INC.'S LIABILITY
FOR ANY SUCH DAMAGES EVER EXCEED THE PRICE PAID FOR THE LICENSE TO
USE THE SOFTWARE, REGARDLESS OF THE FORM OF THE CLAIM. THE PERSON
USING THE SOFTWARE BEARS ALL RISK AS TO THE QUALITY AND
PERFORMANCE OF THE SOFTWARE.
Some states do not allow the exclusion of the limit of liability
for consequential or incidental damages, so the above limitation
may not apply to you.
This agreement shall be governed by the laws of the State of
Alabama and shall inure to the benefit of Marshallsoft Computing,
Inc. and any successors, administrators, heirs and assigns. Any
action or proceeding brought by either party against the other
arising out of or related to this agreement shall be brought only
in a STATE or FEDERAL COURT of competent jurisdiction located in
Madison County, Alabama. The parties hereby consent to in personam
jurisdiction of said courts.
9.0 Revision History
Version 1.0 -- 10 August 1992 -- original release.
PPL4C Users Manual Page 21
10.0 Other MarshallSoft Computing Products
10.1 The Personal Communications Library for C
The Personal Communications Library for the C Language (PCL4C) is
an asynchronous communications library designed for experienced
software developers programming in C. Four compilers are
supported: Microsoft Optimizing C, Microsoft Quick C, Borland
Turbo C, and MIX Power C. An IBM PC/XT/AT or compatible is
required. The PCL features:
o SMALL, COMPACT, MEDIUM & LARGE memory models.
o 32 communications and support functions.
o Support for the high performance INS16550 UART.
o Supports hardware (RTS/CTS) flow control.
o Interrupt driven receiver.
o Supports 300 baud to 115,200 baud.
o Supports COM1, COM2, COM3, and COM4.
o Adjustable receive queues from 8 bytes to 32 KB.
o Control-BREAK error exit.
o 17 communications error conditions trapped.
o Allows 2 ports to run concurrently.
o Complete modem control & status.
o Written in assembly language for small size & high speed.
o Terminal program featuring XMODEM, YMODEM, & YMODEM-G.
The Personal Communications Library for C (PCL4C) is available for
$45 plus $3 S&H ($6 S&H overseas). It may be ordered at the same
time as the Personal Protocol Library for $65 plus $3.50 S&H ($7
overseas).
10.2 The Personal Communications Library for Pascal
The Personal Communications Library for Pascal (PCL4P) is a Turbo
Pascal version of the Personal Communications Library for C, and
is available for $45 plus $3 S&H ($6 S&H overseas). It contains
the same library functions, example programs, documentation, and
user support as the C version.
PPL4C Users Manual Page 22
